/**
  ******************************************************************************
  * @file    dev_flash.h
  * @author  Yun
  * @version V1.0.0
  * @date    2025-02-13
  * @brief   FLASH设备驱动模块头文件
  * @license EULA (End User License Agreement)
  *          Copyright (c) 2025 星瑜科技自动化 Co., Ltd. All rights reserved.
  ******************************************************************************
  */

#ifndef FRAMEWORK_DEV_FLASH_H
#define FRAMEWORK_DEV_FLASH_H

#ifdef __cplusplus
extern "C" {
#endif

/*---------------------- Includes ----------------------*/
#include "dev_common_type.h"
#include "flash_interface.h"
/*---------------------- 类型定义 ----------------------*/
/**
  * @brief  FLASH数据类型枚举
  */
enum Dev_Flash_Data_Type{
    DEV_FLASH_DATA_U8 = 0,   /*!< 8位无符号数据 */
    DEV_FLASH_DATA_U16,      /*!< 16位无符号数据 */
    DEV_FLASH_DATA_U32       /*!< 32位无符号数据 */
};

/**
  * @brief  FLASH设备配置结构体
  */
typedef struct Dev_Flash_Config {
    Flash_Interface_TypeDef* pstDevFlashInterface;  /*!< FLASH操作接口指针 */
    uint8_t u8InitState:1;                       /*!< 初始状态 */
    uint8_t u8RunState:1;                            /*!< 运行状态 */
    uint8_t u8LockState:1;                          /*!< 锁定状态 */
    uint8_t uReserved;                         /*!< 保留 */
} Dev_Flash_Config_TypeDef;

/*---------------------- 设备操作API ----------------------*/
/**
  * @brief  注册FLASH设备
  * @param  pstDevFlashInterface: FLASH接口指针
  * @param  u32FlashBaseCfg: FLASH基地址
  * @param  u32FlashPageSizeCfg: FLASH页大小（字节）
  * @param  u32FlashSizeCfg: FLASH总容量（字节）
  * @retval DEV_Status_TypeDef 操作状态码
  * @note   该函数必须优先于其他操作调用
  */
uint8_t Dev_Flash_Register(Flash_Interface_TypeDef* pstDevFlashInterface,
                           uint32_t u32FlashBaseCfg,
                           uint32_t u32FlashPageSizeCfg,
                           uint32_t u32FlashSizeCfg);

/**
  * @brief  FLASH读取操作
  * @param  u32Addr: 读取起始地址
  * @param  pBuffer: 数据缓存指针
  * @param  u32Len: 读取长度（字节）
  * @param  u8Mode: 操作模式
  * @retval DEV_Status_TypeDef 操作状态码
  * @note   地址和长度必须满足FLASH对齐要求
  */
uint8_t Dev_Flash_Read(uint32_t u32Addr,
                       void* pBuffer,
                       uint32_t u32Len,
                       uint8_t  u8Mode);

/**
  * @brief  FLASH擦除操作
  * @param  u32Addr: 擦除起始地址
  * @param  u32Len: 擦除长度（字节）
  * @retval DEV_Status_TypeDef 操作状态码
  * @note   擦除操作以页为单位，实际擦除范围可能大于请求长度
  */
uint8_t Dev_Flash_Erase(uint32_t u32Addr, uint32_t u32Len);

/**
  * @brief  FLASH写入操作
  * @param  u32Addr: 写入起始地址
  * @param  pBuffer: 数据缓存指针
  * @param  u32Len: 写入长度（字节）
  * @param  u8Mode: 操作模式
  * @retval DEV_Status_TypeDef 操作状态码
  * @note   写入前必须确保目标区域已被擦除
  */
uint8_t Dev_Flash_Write(uint32_t u32Addr,
                        void* pBuffer,
                        uint32_t u32Len,
                        uint8_t  u8Mode);

#ifdef __cplusplus
}
#endif

#endif /* FRAMEWORK_DEV_FLASH_H */

/************************ (C) COPYRIGHT 星瑜科技自动化 *****END OF FILE****/
